Makefile: Regularise subdir targets and their dependencies

Makefile: Regularise subdir targets and their dependencies

Recent changes to this Makefile have broken some build targets, and
some parallel builds.

Looking at it, I think I have identified the undocumented design
intent in the top-level Makefile.  So in this patch I document it, and
also make it true.

In detail:

 * Add a comment with the new design intent
 * Get rid of the ad-hoc rules for recursing into tools/include,
   and replace them with a pattern rule
 * Add an appropriate dependency on TARGET-tools-public-headers from
   TARGET-tools and TARGET-stubdom (but not dist-*).
 * Get rid of all the separate invocations of $(MAKE) -C tools/include
   which are now obsolete
 * Un-deprecate the simple `tools' etc. targets (aliases for `dist-tools')
   which we seem not to be making any effort to get rid of

I have verified with the following shell script that after my change,
the tree producese the same results for various build targets as
3fafdc28eb98 (before the Makefile-hacking started).

My tests failed as expected for make -C tools, both before and after.

Separately, there is a bug in the Makefiles that `make distclean-tools'
fails.  I have not investigated that bug in detail.

    #!/bin/bash

    set -e
    set -o pipefail

    listings=../listings

    rm -rf $listings
    mkdir $listings

    chks () {
         reskey="C$subdir $*"
         reskey="${reskey// /_}"
         reskey="${reskey//\//:}"
         lk=$listings/$reskey
         for suffix in '' -xen -tools -stubdom -docs; do
             case "$subdir:$suffix" in
             .:*) ;;
             *:) ;;
             *) continue;;
             esac
             git clean -qxdff
             rm -rf $output
             printf '%s' "running -C$subdir suffix=$suffix "
             case "$subdir $suffix" in
             *xen*) ;;
             *) printf 'configure '; ./configure >$lk.cfg 2>&1 ;;
             esac
             fail=''
             for targ in $*; do
                 realtarg=$targ$suffix
                 printf '%s ' "$realtarg"
                 if ! make -C $subdir -j10 $realtarg >${lk}_${realtarg}.log 2>&1
                 then
                    fail=$realtarg
                    break
                 fi
             done
             if [ "$fail" ]; then
               echo fail!
               echo "$fail failed" >$lk.list
             else
               echo ok.
               (test ! -e "$output" || find $output) |sort >$lk.list
             fi
        done
    }

    subdirs='. xen docs tools'

    output=$PWD/dist
    for subdir in $subdirs; do
        chks build clean distclean
    done

    output=$PWD/dist
    subdir=.
    chks dist

    export DESTDIR=$PWD/destdir
    output=$PWD/destdir
    for subdir in $subdirs; do
        chks install
    done

And the output:

    (64)iwj@mariner:~/work/xen.git$ ~/junk/chks
    running -C. suffix= configure build clean distclean ok.
    running -C. suffix=-xen build-xen clean-xen distclean-xen ok.
    running -C. suffix=-tools configure build-tools clean-tools distclean-tools fail!
    running -C. suffix=-stubdom configure build-stubdom clean-stubdom distclean-stubdom ok.
    running -C. suffix=-docs configure build-docs clean-docs distclean-docs ok.
    running -Cxen suffix= build clean distclean ok.
    running -Cdocs suffix= configure build clean distclean ok.
    running -Ctools suffix= configure build fail!
    running -C. suffix= configure dist ok.
    running -C. suffix=-xen dist-xen ok.
    running -C. suffix=-tools configure dist-tools ok.
    running -C. suffix=-stubdom configure dist-stubdom ok.
    running -C. suffix=-docs configure dist-docs ok.
    running -C. suffix= configure install ok.
    running -C. suffix=-xen install-xen ok.
    running -C. suffix=-tools configure install-tools ok.
    running -C. suffix=-stubdom configure install-stubdom ok.
    running -C. suffix=-docs configure install-docs ok.
    running -Cxen suffix= install ok.
    running -Cdocs suffix= configure install ok.
    running -Ctools suffix= configure install fail!
    (64)iwj@mariner:~/work/xen.git$

CC: Wei Liu <wei.liu2@citrix.com>
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Tested-by: M A Young <m.a.young@durham.ac.uk>
Tested-by: Andrew Cooper <andrew.cooper3@citrix.com>
Release-acked-by: Julien Grall <julien.grall@arm.com>